<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Async search | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="search.html" title="Search APIs">
<link rel="prev" href="search-request-body.html" title="Request Body Search">
<link rel="next" href="scroll-api.html" title="Scroll API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="search.html">Search APIs</a></span>
»
<span class="breadcrumb-node">Async search</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-request-body.html">« Request Body Search</a>
</span>
<span class="next">
<a href="scroll-api.html">Scroll API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="async-search"></a>Async search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/async-search.asciidoc">edit</a><a class="xpack_tag" href="/subscriptions"></a>
</h2>
</div></div></div>
<p>The async search API let you asynchronously execute a
search request, monitor its progress, and retrieve  partial results
as they become available.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="submit-async-search"></a>Submit async search API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/async-search.asciidoc">edit</a>
</h3>
</div></div></div>
<p>Executes a search request asynchronously. It accepts the same
parameters and request body as the <a class="xref" href="search-search.html" title="Search API">search API</a>.</p>
<a id="submit-async-search-date-histogram-example"></a><div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /sales*/_async_search?size=0
{
    "sort" : [
      { "date" : {"order" : "asc"} }
    ],
    "aggs" : {
        "sale_date" : {
             "date_histogram" : {
                 "field" : "date",
                 "calendar_interval": "1d"
             }
         }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1980.console"></div>
<p>The response contains an identifier of the search being executed.
You can use this ID to later retrieve the search’s final results.
The currently available search
results are returned as part of the <a class="xref" href="search-search.html#search-api-response-body" title="Response body"><code class="literal">response</code></a> object.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=", <a id="CO620-1"></a><i class="conum" data-value="1"></i>
  "is_partial" : true, <a id="CO620-2"></a><i class="conum" data-value="2"></i>
  "is_running" : true, <a id="CO620-3"></a><i class="conum" data-value="3"></i>
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986,
  "response" : {
    "took" : 1122,
    "timed_out" : false,
    "num_reduce_phases" : 0,
    "_shards" : {
      "total" : 562, <a id="CO620-4"></a><i class="conum" data-value="4"></i>
      "successful" : 3, <a id="CO620-5"></a><i class="conum" data-value="5"></i>
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 157483, <a id="CO620-6"></a><i class="conum" data-value="6"></i>
        "relation" : "gte"
      },
      "max_score" : null,
      "hits" : [ ]
    }
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Identifier of the async search that can be used to monitor its progress,
retrieve its results, and/or delete it</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>When the query is no longer running, indicates whether the search failed
or was successfully completed on all shards. While the query is being
executed, <code class="literal">is_partial</code> is always set to <code class="literal">true</code></p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Whether the search is still being executed or it has completed</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p>How many shards the search will be executed on, overall</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-5"><i class="conum" data-value="5"></i></a></p>
</td>
<td align="left" valign="top">
<p>How many shards have successfully completed the search</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO620-6"><i class="conum" data-value="6"></i></a></p>
</td>
<td align="left" valign="top">
<p>How many documents are currently matching the query, which belong to the
shards that have already completed the search</p>
</td>
</tr>
</table>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Although the query is no longer running, hence <code class="literal">is_running</code> is set to
<code class="literal">false</code>, results may be partial. That happens in case the search failed after
some shards returned their results, or when the node that is coordinating the
 async search dies.</p>
</div>
</div>
<p>It is possible to block and wait until the search is completed up to a certain
timeout by providing the <code class="literal">wait_for_completion_timeout</code> parameter, which
defaults to <code class="literal">1</code> second. When the async search completes within such timeout,
the response won’t include the ID as the results are not stored in the cluster.
The <code class="literal">keep_on_completion</code> parameter, which defaults to <code class="literal">false</code>, can be set to
<code class="literal">true</code> to request that results are stored for later retrieval also when the
search completes within the <code class="literal">wait_for_completion_timeout</code>.</p>
<p>You can also specify how long the async search needs to be
available through the <code class="literal">keep_alive</code> parameter, which defaults to <code class="literal">5d</code> (five days).
Ongoing async searches and any saved search results are deleted after this
period.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When the primary sort of the results is an indexed field, shards get
sorted based on minimum and maximum value that they hold for that field,
hence partial results become available following the sort criteria that
was requested.</p>
</div>
</div>
<p>The submit async search API supports the same <a class="xref" href="search-search.html#search-search-api-query-params" title="Query parameters">parameters</a>
as the search API, though some have different default values:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">batched_reduce_size</code> defaults to <code class="literal">5</code>: this affects how often partial results
become available, which happens whenever shard results are reduced. A partial
reduction is performed every time the coordinating node has received a certain
number of new shard responses (<code class="literal">5</code> by default).
</li>
<li class="listitem">
<code class="literal">request_cache</code> defaults to <code class="literal">true</code>
</li>
<li class="listitem">
<code class="literal">pre_filter_shard_size</code> defaults to <code class="literal">1</code> and cannot be changed: this is to
enforce the execution of a pre-filter roundtrip to retrieve statistics from
each shard so that the ones that surely don’t hold any document matching the
query get skipped.
</li>
<li class="listitem">
<code class="literal">ccs_minimize_roundtrips</code> defaults to <code class="literal">false</code>, which is also the only
supported value
</li>
</ul>
</div>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>Async search does not support <a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a>
nor search requests that only include the  <a class="xref" href="search-suggesters.html" title="Suggesters">suggest section</a>.
cross-cluster search is supported only with <a class="xref" href="modules-cross-cluster-search.html#ccs-min-roundtrips" title="Minimize network roundtrips"><code class="literal">ccs_minimize_roundtrips</code></a>
set to <code class="literal">false</code>.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="get-async-search"></a>Get async search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/async-search.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The get async search API retrieves the results of a previously submitted
async search request given its id. If the Elasticsearch security features are enabled.
the access to the results of a specific async search is restricted to the user
that submitted it in the first place.</p>
<a id="get-async-search-date-histogram-example"></a><div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=</pre>
</div>
<div class="console_widget" data-snippet="snippets/1981.console"></div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "id" : "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
  "is_partial" : true, <a id="CO621-1"></a><i class="conum" data-value="1"></i>
  "is_running" : true, <a id="CO621-2"></a><i class="conum" data-value="2"></i>
  "start_time_in_millis" : 1583945890986,
  "expiration_time_in_millis" : 1584377890986, <a id="CO621-3"></a><i class="conum" data-value="3"></i>
  "response" : {
    "took" : 12144,
    "timed_out" : false,
    "num_reduce_phases" : 46, <a id="CO621-4"></a><i class="conum" data-value="4"></i>
    "_shards" : {
      "total" : 562, <a id="CO621-5"></a><i class="conum" data-value="5"></i>
      "successful" : 188,
      "skipped" : 0,
      "failed" : 0
    },
    "hits" : {
      "total" : {
        "value" : 456433,
        "relation" : "eq"
      },
      "max_score" : null,
      "hits" : [ ]
    },
    "aggregations" : { <a id="CO621-6"></a><i class="conum" data-value="6"></i>
      "sale_date" :  {
        "buckets" : []
      }
    }
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>When the query is no longer running, indicates whether the search failed
or was successfully completed on all shards. While the query is being
executed, <code class="literal">is_partial</code> is always set to <code class="literal">true</code></p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Whether the search is still being executed or it has completed</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>When the async search will expire</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-4"><i class="conum" data-value="4"></i></a></p>
</td>
<td align="left" valign="top">
<p>Indicates how many reductions of the results have been performed. If this
number increases compared to the last retrieved results, you can expect
additional results included in the search response</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-5"><i class="conum" data-value="5"></i></a></p>
</td>
<td align="left" valign="top">
<p>Indicates how many shards have executed the query. Note that in order for
shard results to be included in the search response, they need to be reduced
first.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO621-6"><i class="conum" data-value="6"></i></a></p>
</td>
<td align="left" valign="top">
<p>Partial aggregations results, coming from the shards that have already
completed the execution of the query.</p>
</td>
</tr>
</table>
</div>
<p>The <code class="literal">wait_for_completion_timeout</code> parameter can also be provided when calling
the Get Async Search API, in order to wait for the search to be completed up
until the provided timeout. Final results will be returned if available before
the timeout expires, otherwise the currently available results will be
returned once the timeout expires. By default no timeout is set meaning that
the currently available results will be returned without any additional wait.</p>
<p>The <code class="literal">keep_alive</code> parameter specifies how long the async search should be
available in the cluster. When not specified, the <code class="literal">keep_alive</code> set with the
corresponding submit async request will be used. Otherwise, it is possible to
override such value and extend the validity of the request. When this period
expires, the search, if still running, is cancelled. If the search is
completed, its saved results are deleted.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="delete-async-search"></a>Delete async search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/async-search.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can use the delete async search API to manually delete an async search
by ID. If the search is still running, the search request will be cancelled.
Otherwise, the saved search results are deleted.</p>
<a id="delete-async-search-date-histogram-example"></a><div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">DELETE /_async_search/FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=</pre>
</div>
<div class="console_widget" data-snippet="snippets/1982.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="search-request-body.html">« Request Body Search</a>
</span>
<span class="next">
<a href="scroll-api.html">Scroll API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
